[#217] feat: tag-driven workflows — opt-in automation on tagged issues - #474

Tier = max(assessed) = risk:red, unchanged. Cost = orange, unchanged. Review value confirms refinement; nothing raised.

• --card → identifierText at parse time and isSafeId again in card-lock.ts:43 where the path is actually built (defence at the point of use, not only at the edge).
• Each --card-tags entry → isSafePromptText; an empty entry inside the list HALTs (parser.ts), an empty whole value is data (ADL recorded).
• ## Workflows tag → assertLabelValue (the same rule ## Eligibility gets, now one implementation in policy-sections.ts rather than two — a real improvement carried by this PR).
• Workflow name → isSafeId, because it is both spliced into an invocation and used as a path segment.
• Audit values are newline-flattened (dispatch-audit.ts:110), so no field can forge a second trail line.

• decideDispatch evaluates mapping → eligibility → routing in that order, verified by dispatch.test.ts:87-101.
• Stale-label trust is an accepted, recorded trade-off (ADR-024 § Trade-offs) — not a silent one.
• The lock's cross-host limitation is recorded in the same section, then contradicted by github-automation.md:211-213.

Critical (must fix before merge)

• none.

Major (must fix before merge)

• .pair/knowledge/guidelines/collaboration/automation/github-automation.md:251 (+ dataset mirror) — [ -n "$record" ] && gh issue comment … is the last command of the step, so when nothing was dispatched the compound returns 1 and the step exits 1. GitHub's default run shell is bash -e {0}. Concrete case: an untagged issue is labelled → pair run exits 0 with no DISPATCH-RECORD: line → record="" → the job goes red. That is exactly the case the same file's "Untagged is not a case the adapter has to handle" paragraph promises is silent, and AC2's whole point ("nothing runs on that issue"). Every unmapped label edit on the board produces a failed workflow run and a failure notification. Evidence, reproduced: printf 'record=""\n[ -n "$record" ] && echo posted\n' | bash -e → exit 1. Fix: if [ -n "$record" ]; then gh issue comment "$CARD" --body "$record"; fi.
• .pair/knowledge/guidelines/collaboration/automation/github-automation.md:239 (+ dataset mirror) — pair run … | tee dispatch.log runs under bash -e without pipefail (GH only adds -eo pipefail when the step declares shell: bash), so the pipeline's status is tee's. Concrete case: ## Workflows maps auto-dev ⇒ pair-loop and pair-loop is not installed → decideDispatch HALTs, pair run exits 1 → the job reports success. The adoption-fix HALT that the design deliberately chose over a silent fallback never reaches a human, and the team's cards stop being processed with a green tick on every run. Evidence, reproduced: printf 'false | tee /dev/null\n' | bash -e → exit 0; same script under bash -eo pipefail → exit 1. Fix: add shell: bash to the step (or set -o pipefail as its first line).
• .pair/knowledge/guidelines/collaboration/automation/github-automation.md:211-213 (+ dataset mirror) — the concurrency: comment states the host group is "NOT the safety guard: the per-card lock inside pair run is what guarantees one run per card, and it holds even when two triggers come from two different workflows, two repositories, or a manual invocation on the box." In this workflow that is false, and it directly contradicts ADR-024's own recorded limitation ("The lock is filesystem-local: two runners on different machines sharing no working area can still collide"). Each ubuntu-latest job does a fresh actions/checkout, so <working_path>/automation/locks/ is always empty — the lock always succeeds. Concrete case: a team reads that sentence and adds a second trigger (workflow_dispatch, or an issue_comment job) outside the pair-dispatch-<issue> group; both jobs acquire the lock on their own runners and two agents drive card 217 on the same branch and PR — the precise race the guard exists for. Fix: state that on ephemeral runners the host concurrency group is the cross-job guard (which is why cancel-in-progress: false matters), and that the per-card lock covers collisions within one working area — the persistent-daemon deployments of the tutorial's Options A–C. Cite ADR-024's limitation instead of contradicting it.

Minor (must fix before merge — same bar as Major, just lower impact)

• apps/pair-cli/src/commands/run/handler.ts:278-286 — a throw from driveRun releases the lock in finally but writes no end record. The guideline this PR ships states "Every dispatch decision — start, skip, end — is appended to the run's ## Audit Location file". Concrete case: the engine spawn rejects mid-run → the trail holds … event=start card=217 tag=auto-dev workflow=pair-loop and nothing after it; the operator reading the trail the next morning (the module docstring's stated use) cannot distinguish a crashed run from one still in flight, and the lock is gone so the filesystem gives no second signal. handler.test.ts:688 asserts lock events only, so nothing catches it. Fix: catch → record(… { event: 'end', outcome: 'crashed' }) → rethrow, and extend that test to assert the record.
• apps/pair-cli/src/commands/run/handler.ts:271 — join(context.workingArea, 'automation/locks') re-hardcodes the path that card-lock.ts:22 owns as the non-exported LOCK_DIRECTORY. Concrete case: someone relocates the lock directory in card-lock.ts; the burst-skip message keeps naming the old path, so the operator is sent to a directory that does not exist — defeating the exact purpose card-lock.ts:26 states for it ("printed, so a stale lock is findable without guessing"). No test compares the two. Fix: export LOCK_DIRECTORY (or have the acquirer return the intended path) and use it at the call site.
• apps/pair-cli/src/commands/run/card-lock.ts:40-83 — a stale lock has no recovery path and no operator documentation. finally covers exceptions, not SIGKILL, OOM, or a host job timeout. Concrete case: on a persistent runner (the tutorial's Options A–C — a VPS daemon, the deployment where the lock actually is the guard) the daemon is killed mid-run; <working_path>/automation/locks/217/ survives forever; every later trigger on card 217 prints run-in-progress, exits 0, and appends a skip line — automation is permanently and silently off for that card, with no alert, and github-automation.md's "Before wiring the trigger" checklist never mentions looking. holder.json already records pid and acquiredAt but nothing reads them. Fix: surface the holder's age in the skip detail (the data is already written) and add the one-line manual-clear instruction to the KB's operator checklist.
• apps/website/content/docs/tutorials/unattended-delivery.mdx:35, 251, 273 — three stale numeric claims left behind by this PR. :35 still says "Six independent sections" while the same PR updates the KB to "seven sections"; :251 introduces ## Workflows as "a sixth section", a number Step 1's own list already spends; :273 calls the shipped GitHub Actions job "20 lines" when the snippet it points at is ~40. Concrete case: a reader who followed Step 1 believes they already have six sections, reaches Option D, and cannot tell which section they are being asked to add. Fix: renumber to seven / "a seventh section", and drop or correct the line count.

Questions (informational, never blocking)

• apps/pair-cli/src/commands/run/dispatch.ts:72 — assertWorkflowsInstalled runs before the eligibility and routing checks, so one mapping line naming an uninstalled workflow HALTs every trigger on the whole board, including cards that are ineligible or carry no mapped tag. The comment argues this deliberately ("finding out only on the card that happens to carry that tag would make the failure depend on which trigger fired first"), and I agree with the reasoning — flagging only because combined with Major 2 the blast radius is invisible: every job goes green while nothing is dispatched anywhere. Worth confirming this is the intended blast radius once Major 2 is fixed.
• apps/pair-cli/src/commands/run/handler.ts:317 — only start is emitted as a DISPATCH-RECORD: line, so only starts can be posted on the card; skip and end reach the audit file only. AC3 requires the run start on the issue, so this meets the AC, and suppressing a comment per skipped label edit is clearly the right call for noise. But T3 in the story's task breakdown reads "Audit trail (start/end/skip comments on issues)". Confirm the narrower reading is deliberate — if so it is worth one sentence in the guideline, since it is the kind of thing a future adapter author will re-litigate.

• The purity property is mechanized, not asserted: routing-purity.test.ts bans tier vocabulary, classification imports, shape inspection and regexes in the routing core, and allowlists every method callable on a tags collection. That is the DoD line "grep-verifiable: no classification criteria in workflow code" turned into a build failure, and it is the single best thing in this PR.
• policy-sections.ts is the right extraction at the right moment — the label rules now have one implementation instead of two, and the diff shows the messages are byte-identical, so the refactor is verifiably behaviour-preserving.
• The e2e suite drives five triggers against one real project directory through the real command registry with only the engine spawn injected — real lock, real audit file. That is the "populated test board" the story's DoD asks for, not a mock of one.
• Both ADLs record decisions that would otherwise look like violations (node:fs in a FileSystemService codebase; one flag that accepts empty). ADR-024 records the two rejected options and the four limitations of the chosen one, including the lock's cross-host scope — which is why Major 3 reads as a doc slip rather than a missed risk.

• AC1 (mapping routes each card to its workflow) — workflow-mapping.ts + dispatch.ts; dispatch.test.ts:26-47, handler.test.ts:498, e2e :147.
• AC2 (no mapped tag ⇒ nothing runs; grep-verifiable absence of default-on) — dispatch.ts:92-98, routing-purity.test.ts, dispatch.test.ts:49-86, e2e :147. Met in the core; the shipped adapter turns this case red — Major 1.
• AC3 (single entry point; run start recorded on the issue) — pair run --card; DISPATCH-RECORD: + adapter post. Met in the core; the posting step is Major 1.
• AC4 (no mapping section ⇒ "no mapping declared", clean exit) — dispatch.ts:66-68, handler.test.ts:562, e2e :205.
• BR3 (eligibility before routing) — dispatch.ts:74-89, dispatch.test.ts:87-101.
• Edge cases: unknown workflow ⇒ HALT; two mapped tags without precedence ⇒ HALT; burst ⇒ skip not queue. All three tested.

• Coverage: one suite per module + purity guard + e2e; HALT triggers enumerated 1:1 against the guideline's list.
• Edge/error scenarios tested (including "releases the lock even when the run throws").
• Quality gates: PASS — I re-ran the new suites at 12846737: routing-purity 7, workflow-mapping 20, parser 56, dispatch 16, dispatch-audit 10, card-lock 8 → 117 passed. (handler.test.ts did not run in my sandbox for an environment reason — an adm-zip resolution failure from the way I linked node_modules into a detached worktree — not a PR defect.)
• Gap: no test asserts the end record on the throwing path (Minor 1).

• Degradation level: 1 — no deviation from adopted patterns.
• ADR-024 + two ADLs present and substantive; architecture.md and way-of-working.md updated to match. No new dependency, so tech-stack.md is untouched correctly.
• KB ↔ dataset mirror verified: README.md and github-automation.md byte-identical; automation-policy.md differs only on four pre-existing /setup-harness lines untouched by this PR — the new ## Workflows section mirrors byte-for-byte.
• .pair/adoption/tech/automation.md deliberately left without a ## Workflows section, so this repo exercises the absent-section default. Consistent with the ADR's stated Adoption Impact.

• The lock is filesystem-local and cannot coordinate across machines. Recorded in ADR-024 as an accepted limitation and out of this story's isolation model — surfaced, not blocking. Note that Major 3 is not this: it is the KB claiming the opposite of what the ADR records.

• KB schema, reference adapter, website concepts/reference/tutorial, llms.txt, guidelines catalog — all updated, with conformance tests guarding the normative claims.
• Three doc defects above (Major 1–3 in the adapter, Minor 4 in the tutorial).

• No hot path touched; one extra section parse per run over a file already read.
• Rollback is trivial: absent ## Workflows is the shipped default, so the feature is off until a project opts in.

• Bare pair <cmd> invocations renamed to pair-cli; docs staleness passes.
• Port onto main preserved post-base additions and resolved merge markers compositionally.
• Test pin updated.

• Mapping, no-default route, eligibility-before-routing, lock, audit and fail-fast adoption errors are otherwise coherent with ADR-024 and story Tag-driven workflows (opt-in automation on tagged issues) #217.
• Schema, catalog, adapter documentation and generated indexes are present.

• Exact PR head 83fa9c53d1d159e7b66bf07c0fdf68f01e130270 checked in a clean detached worktree.
• pnpm quality-gate PASS (exit 0), including typecheck, tests, lint, workflow tests, format, hygiene, smoke, docs/skills/index checks and duplication threshold.
• No regression test covers a host label containing a comma across adapter → parser → dispatcher.